Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Using named widget pools

Here’s a simple example of using a named widget pool:

DEFINE VARIABLE hButton AS HANDLE       NO-UNDO. CREATE WIDGET-POOL "ButtonPool". CREATE BUTTON hButton IN WIDGET-POOL "ButtonPool". DELETE WIDGET-POOL "ButtonPool". MESSAGE "What is the button handle value?" hButton SKIP         "Is the button still there?" VALID-HANDLE(hButton).

The code creates a widget pool named ButtonPool. Then it creates a button in that pool. It then deletes the pool. The handle variable itself is still defined, of course, but its value now points to an invalid object because the memory is gone, as indicated by the message shown in Figure 18–8.

Figure 18–8: Button handle message

By default, a widget pool is deleted when the procedure that creates it terminates. If you create a named widget pool, you can use the PERSISTENT keyword to keep the pool around after the procedure terminates. This creates another level of memory management responsibility for you, because now you need to remember to delete the widget pool when you’re done with it. Otherwise, it lasts until the end of the session just like the default pool does.

The NO-ERROR keyword can prevent an error message if you try to create a pool with a name that is already in use or if you try to delete one that has already been deleted.

Now look at some variations on this theme. In this example, the code creates a named widget pool and a button in that pool, but then deletes the unnamed pool:

DEFINE VARIABLE hButton AS HANDLE NO-UNDO. CREATE WIDGET-POOL "ButtonPool". CREATE BUTTON hButton IN WIDGET-POOL "ButtonPool". DELETE WIDGET-POOL. MESSAGE "What is the button handle value?" hButton SKIP "Is the button still there?" VALID-HANDLE(hButton).

A DELETE WIDGET-POOL statement without a pool name deletes the unnamed widget pool created most recently in that routine, where routine means a main procedure block, internal procedure, or trigger block. Progress does not display an error if there is no unnamed pool to delete, as you can see from this example. When you run the code, the button is still there because its pool wasn’t deleted, as shown in Figure 18–9.

Figure 18–9: Button handle message

The default session pool is never deleted until the session ends.

In this next variation, you create the button in the unnamed pool and then delete the named pool:

DEFINE VARIABLE hButton AS HANDLE"      NO-UNDO. CREATE WIDGET-POOL "ButtonPool". CREATE BUTTON hButton. /* No longer IN WIDGET-POOL "ButtonPool". */ DELETE WIDGET-POOL "ButtonPool". MESSAGE "What is the button handle value?" hButton SKIP         "Is the button still there?" VALID-HANDLE(hButton).

Is the button still there after you delete the named pool? Yes, as shown in Figure 18–10, because it wasn’t allocated in the named pool you deleted.

Figure 18–10: Another button handle message

Remember that a nonpersistent widget pool, whether named or unnamed, is automatically deleted when its procedure goes out of scope. Thus, a DELETE WIDGET-POOL statement at the end of such a procedure is optional. But it’s certainly not a bad idea to include the statement to confirm that the pool is going away with the procedure.